<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<html lang="en">

<head>
	<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
	<title>jQuery.twFile</title>
	<link rel="stylesheet" type="text/css" href="styles/main.css">
</head>

<body>
	<h1>jQuery.twFile</h1>
	<p>
		This <a href="http://jquery.com">jQuery</a> plugin provides access to
		the local file system (for documents loaded from a <code>file://</code>
		URI) to load and save file contents from the browser.
	</p>

	<p>
		The code is based on <a href="http://tiddlywiki.com">TiddlyWiki</a>'s
		self-saving capabilities.
	</p>

	<p id="TiddlySaver">
		Note that the <a href="http://www.tiddlywiki.com/TiddlySaver.jar">TiddlySaver</a>
		applet is required on Opera and WebKit-based browsers (Safari, Chrome).
		The applet has to be present in the same folder as the respective HTML document.
	</p>

	<h2>Source</h2>
	<p>
		The source code is currently hosted in TiddlyWiki's
		<a href="http://svn.tiddlywiki.org/Trunk/core/jquery/plugins/jQuery.twFile.js">Subversion repository</a>.
	</p>
	<p>
		<a href="http://groups.google.com/group/TiddlyWikiDev/">Feedback</a> is welcome.
	</p>

	<h2>API Summary</h2>
	<ul>
		<li>
			<p><code>$.twFile.load(filePath)</code>: load contents from file</p>
		</li>
		<li>
			<p><code>$.twFile.save(filePath, content)</code>: save contents to file</p>
		</li>
		<li>
			<p><code>$.twFile.copy(dest, source)</code>: duplicate existing file</p>
			<p><strong>N.B.:</strong> This is not supported on all browsers.</p>
		</li>
		<li>
			<p>
				<code>$.twFile.convertUriToLocalPath(filePath)</code>:
				normalizes specified absolute file path
			</p>
		</li>
	</ul>
	<p>
		<strong>N.B.:</strong> All file paths must be absolute (e.g.
		<code>/tmp/foo.txt</code> or <code>C:\temp\foo.txt</code>).
	</p>
	<p>(full documentation in the code comments)</p>

	<h2>Limitations</h2>
	<ul>
		<li>
			plugin unavailable until
			<a href="http://docs.jquery.com/Events/ready">document.ready</a>
			handlers have completed
			<p>
				Since the TiddlySaver applet cannot be injected synchronously
				into the document, this is done asynchronously during
				<code>document.ready</code> processing.
			</p>
			<p>
				This means that the plugin is not guaranteed to work properly
				until after all these handlers have completed.
			</p>
		</li>
		<li>
			currently unreliable UTF-8 support on Internet Explorer
			<p>
				The plugin is designed to work with UTF-8 encoded text files.
				However, support in Internet Explorer is broken, and can only
				reliably save files that are encoded with the ANSI subset of
				UTF-8. In the case of HTML files, this problem can often be
				avoided by using HTML entity encodings.
			</p>
		</li>
	</ul>

	<h2>Internals</h2>
	<p>
		Internally, the plugin uses four separate drivers to implement the functionality on different browsers:
		<ul>
			<li>
				<code>activeX</code>: uses the <code>FileSystemObject</code> built into Internet Explorer 5 and above
			</li>
			<li>
				<code>mozilla</code>: uses the XUL libraries built into Firefox
			</li>
			<li>
				<code>tiddlySaver</code>: uses a custom Java applet that works on Safari, Chrome and Opera
			</li>
			<li>
				<code>javaLiveConnect</code>: uses an ancient (and slow) binding technology to call Java runtime library routines directly - only works on Opera
			</li>
		</ul>
	</p>

	<h2>Demo</h2>
	<p>
		Download <a href="twFileDemo.html">this document</a> (and
		<a href="#TiddlySaver">TiddlySaver</a> if necessary) and open it from
		the local disk.
	</p>
	<p>
		This demo illustrates self-saving capabilities by passing
		<code>document.location.href</code> to <code>$.twFile.convertUriToLocalPath</code>,
		using the return value in load and save functions.
	</p>

</body>

</html>
